home *** CD-ROM | disk | FTP | other *** search
/ Developer CD Series 1995…tember: Reference Library / Dev.CD Sep 95 RL / Dev.CD Sep 95 RL.toast / mac / Technical Documentation / develop / develop Issue 20 code / Scripting the Finder / Finder Snapshot / AppleEventUtilities.h < prev    next >
Encoding:
C/C++ Source or Header  |  1994-10-04  |  11.3 KB  |  348 lines  |  [TEXT/MMCC]
  1. /*
  2.     File:        AppleEventUtilities.h
  3.  
  4.     Contains:    C++ Wrappers for Apple Event manager
  5.  
  6. */
  7.  
  8. #ifndef __APPLEEVENTUTILITIES__
  9. #define __APPLEEVENTUTILITIES__
  10.  
  11. //
  12. // Needed for AEDesc & c.
  13. //
  14. #ifndef __APPLEEVENTS__
  15. #include "AppleEvents.h"
  16. #endif
  17.  
  18. const DescType typeTokenObject = 'tkob';
  19. const DescType cAbstractObject = 'abst';
  20. const DescType cAbstractWindow = 'abwn';
  21.  
  22. // These should be generic types
  23. const typeDateTimeRec = 'dtim';
  24. // const typeLongDateTime = 'ldt ';
  25. const typeLongDateTimeRec = 'ldtr';
  26.  
  27.  
  28. // Use with CreateList:
  29. #define kMakeAEList        false
  30. #define kMakeAERecord    true
  31.  
  32. // Some procedural routines
  33.  
  34. Boolean InterpretCompareResult(DescType comparisonOperator, long key1, long key2 );
  35. Boolean GeneralCompare(DescType comparisonOperator, Ptr data, Size length, Ptr compareWith, Size comparisonLength, Boolean caseSensitive);
  36.  
  37.  
  38. class TTokenDescriptor;
  39.  
  40.  
  41. class TDescriptor
  42.     {    
  43. protected:
  44.     //
  45.     // A TDescriptor is an AEDesc, so it must have
  46.     // two and only two fields, and they must be
  47.     // the descriptor type and the data handle.
  48.     //
  49.     DescType            fDescriptorType;
  50.     Handle                fDataHandle;
  51.     
  52.     //
  53.     // These flags are passed to AEResolve when
  54.     // specific flags are not specified.  This
  55.     // allows an application to define kAEIDoWhose
  56.     // and/or kAEIDoMarking once at startup, and
  57.     // subsequentially call AEResolve without
  58.     // any parameters elsewhere in the code.
  59.     //
  60.     static short        fCallbackFlags;
  61.     
  62. public:
  63.     static void            SetCallbackFlags(short callbackFlags)    { fCallbackFlags = callbackFlags; };
  64.     
  65.     //
  66.     // Construction methods
  67.     //
  68.                         TDescriptor() : fDescriptorType(typeNull), fDataHandle(nil) {};
  69.                         TDescriptor(DescType type, Handle dataHandle) : fDescriptorType(type), fDataHandle(dataHandle) {};
  70.                         // TDescriptor(const TDescriptor desc) : fDescriptorType(desc.DescriptorType()), fDataHandle(desc.DataHandle()) {};
  71.     
  72.     //
  73.     // Dispose
  74.     //
  75.     void                Dispose();
  76.  
  77.     //
  78.     // Conversion operators
  79.     //
  80.     operator            const AEDesc*() const                    { return (const AEDesc*) this; };
  81.     operator            AEDesc*()                                { return (AEDesc*) this; };
  82.     operator            AEDesc()                                { return *((AEDesc*) this); };
  83.     
  84.     //
  85.     // Direct access to descriptor information
  86.     //
  87.     DescType            DescriptorType() const                    { return fDescriptorType; };
  88.     Handle                DataHandle()                            { return fDataHandle; };
  89.     Boolean                IsNullDescriptor() const                { return fDescriptorType == typeNull; };
  90.     Boolean                DataHandleIsNil() const                    { return fDataHandle == nil; };
  91.     
  92.     //
  93.     // Content manipulation
  94.     //
  95.     OSErr                AttemptCoercion(DescType typeToCoerceTo);
  96.     void                CoerceInPlace(DescType typeToCoerceTo);
  97.     TDescriptor            Coerce(DescType typeToCoerceTo) const;
  98.     void                CoerceToStandardType();
  99.     TDescriptor            Clone() const;
  100.     void                CopyDesc(const TDescriptor& desc);
  101.     void                AdoptDesc(TDescriptor& desc);
  102.     void                AdoptHandle(DescType dataType, Handle dataHandle);
  103.     void                CopyData(const DescType typeCode, const Ptr data, const Size length);
  104.  
  105.     void                CreateList(Boolean isRecord = kMakeAEList, Ptr factoringPtr = nil, Size factoredSize = 0);
  106.     void                MakeNull();
  107.     
  108.     //
  109.     // Descriptor creation
  110.     //
  111.     void                MakeBoolean(const Boolean data);
  112.     void                MakeLong(const long data);
  113.     void                MakePoint(const Point& thePoint);
  114.     void                MakePoint(const short h, const short v);
  115.     void                MakeRect(const Rect& theRect);
  116.     void                MakeUnsignedLong(const unsigned long data);
  117.     void                MakeEnumeration(const DescType enumeration);
  118.     void                MakeDescType(const DescType data);
  119.     void                MakeKeyword(const AEKeyword theKeyword);
  120.     void                MakeOrdinal(const DescType data);
  121.     void                MakeTypeOrInteger(const DescType data);
  122.     void                MakeString(Str255 data);
  123.     void                MakeDateTimeRec(const DateTimeRec dateTime);
  124.     void                MakeDateTimeRec(const long dateTime);
  125.     void                MakeLongDateTimeRec(const LongDateRec dateTime);
  126.     void                MakeLongDateTimeRec(const DateTimeRec dateTime);
  127.     void                MakeLongDateTimeRec(LongDateTime lsecs);
  128.     void                MakeLongDateTime(const LongDateTime lsecs);
  129.     void                MakeFSS(const FSSpec& spec);
  130.     void                AdoptAlias(Handle alias);
  131.     void                MakeAlias(FSSpec& spec);
  132.     void                MakeProcessSerialNumber(ProcessSerialNumber psn);
  133.     
  134.     void                MakeObjectSpecifier(DescType desiredClass, TDescriptor container, DescType keyForm, TDescriptor keyData, Boolean disposeInputs);
  135.     void                MakeCompDescriptor(DescType comparisonOperator, DescType propertyIdentifier, TDescriptor compareWith, Boolean disposeInputs);
  136.     
  137.     //
  138.     // Data extraction
  139.     //
  140.     void                GetBlock(Ptr data, Size length, DescType desiredType) const;
  141.     long                GetLong() const;
  142.     Boolean                GetBoolean() const;
  143.     DescType            GetDescType() const;
  144.     AEKeyword            GetKeyword() const;
  145.     DescType            GetEnumeration() const;
  146.     DescType            GetOrdinal() const;
  147.     Point                GetPoint() const;
  148.     Rect                GetRect() const;
  149.     void                GetString(Str255) const;
  150.     DateTimeRec            GetDateTimeRec() const;
  151.     void                GetFSS(FSSpec& spec) const;
  152.  
  153.     Boolean                Compare(DescType comparisonOperator, Str255 withString) const;
  154.     Boolean                Compare(DescType comparisonOperator, TDescriptor& compareWith) const;
  155.     
  156.     //
  157.     // List methods
  158.     //
  159.     // Formerly, we had a separate class, TDescriptorList.
  160.     // Now, however, there is no difference between a TDescriptor
  161.     // and a TDescriptorList
  162.     //
  163.     void                MakeEmptyList();
  164.     void                MakeList();
  165.     
  166.     long                CountItems() const;
  167.     TDescriptor            GetNthDescriptor(long index, DescType desiredType = typeWildCard, AEKeyword* key = nil) const;
  168.  
  169.     void                AddDescriptor(long index, TDescriptor& data);
  170.     void                AddDescriptor(TDescriptor& data);
  171.  
  172.     void                AddData(long index, DescType descType, Ptr data, Size length);
  173.     void                AddData(DescType descType, Ptr data, Size length);
  174.     void                AddLong(long number);
  175.     void                AddType(DescType descType);
  176.  
  177.     void                AppendList(const TDescriptor& list);
  178.     void                AdoptList(TDescriptor* list);
  179.  
  180.     //
  181.     // AERecord methods
  182.     //
  183.     // Formerly, we had a separate class, TAERecord.
  184.     // Now, however, AERecords and AEDescriptors are
  185.     // used interchangably enough that there is really
  186.     // no reason to have a separate class.
  187.     //
  188.     void                MakeAERecord();
  189.  
  190.     TDescriptor GetDescriptor(AEKeyword key, DescType desiredType = typeWildCard);    
  191.     TDescriptor GetOptionalParameter(AEKeyword key, DescType desiredType = typeWildCard);    
  192.     void GetParameterPtr(AEKeyword key, DescType desiredType, DescType *typeCode, Ptr dataPtr, Size maximumSize, Size *actualSize);
  193.     long GetLongParameter(AEKeyword key, DescType desiredType = typeLongInteger);    
  194.     short GetShortParameter(AEKeyword key, DescType desiredType = typeShortInteger);    
  195.  
  196.     TDescriptor GetDirectObject();
  197.     long GetErrorCode();
  198.  
  199.     void PutDescriptor(AEKeyword key, TDescriptor data);
  200.     void PutParameterPtr(AEKeyword key, DescType typeCode, Ptr dataPtr, Size dataSize);
  201.     void PutParameterHandle(AEKeyword key, DescType typeCode, Handle dataHandle);
  202.     void PutLongParameter(AEKeyword key, DescType typeCode, long data);    
  203.     void PutLongParameter(AEKeyword key, long data);    
  204.     void PutShortParameter(AEKeyword key, DescType typeCode, short data);    
  205.     void PutShortParameter(AEKeyword key, short data);    
  206.  
  207.     void PutResult(TDescriptor data);
  208.     void PutErrorCode(long theErr);
  209.     
  210.     //
  211.     // Object support library methods
  212.     //
  213.     TTokenDescriptor    Resolve();    
  214.     TTokenDescriptor    Resolve(short callbackFlags);    
  215.     };
  216.  
  217.  
  218.  
  219. //
  220. // A descriptor loop iterates over every item in a descriptor
  221. // list or an AERecord.
  222. //
  223. class TDescriptorLoop
  224.     {
  225. public:
  226.                         TDescriptorLoop(const TDescriptor* dl) {fDescriptorList = dl; fIndex = 0; fCount = 0; };
  227.     Boolean                Next(TDescriptor& d, AEKeyword* key = nil, Handle* h = nil);
  228.  
  229. private:
  230.     const TDescriptor*        fDescriptorList;
  231.     long                    fIndex;
  232.     long                    fCount;
  233.     };
  234.  
  235. #define FOREACHDESCRIPTOR(listToIterate, descriptor)            \
  236.     TDescriptorLoop loop(listToIterate);                        \
  237.     AEKeyword keyword;                                            \
  238.     while (loop.Next(descriptor, &keyword, nil))
  239.  
  240.  
  241.  
  242.  
  243.  
  244. class TAEvent : public TDescriptor
  245.     {
  246. public:
  247.  
  248.     TAEvent();
  249.     
  250.     //
  251.     // Conversion opperators
  252.     //
  253.     operator const AppleEvent*() const        { return (const AppleEvent*) this; };
  254.     operator AppleEvent*()                    { return (AppleEvent*) this; };
  255.     operator AppleEvent()                    { return *((AppleEvent*) this); };
  256.             
  257.     void MakeAppleEvent(AEEventClass eventClass, AEEventID eventID,
  258.                 const TDescriptor& target, short returnID = kAutoGenerateReturnID, long transactionID = kAnyTransactionID);
  259.     void MakeAppleEvent(AEEventClass eventClass, AEEventID eventID,
  260.                 const ProcessSerialNumber& psn, short returnID = kAutoGenerateReturnID, long transactionID = kAnyTransactionID);
  261.     
  262.     void MakeEventAddressedToSelf(AEEventClass eventClass, AEEventID eventID, short returnID = kAutoGenerateReturnID, long transactionID = kAnyTransactionID);
  263.     void MakeEventAddressedToSystem(AEEventClass eventClass, AEEventID eventID, short returnID = kAutoGenerateReturnID, long transactionID = kAnyTransactionID);
  264.     
  265.     void Send(TAEvent* reply, AESendMode sendMode, AESendPriority sendPriority = kAENormalPriority,
  266.             long timeOutInTicks = kAEDefaultTimeout, AEIdleUPP idleProc = nil, AEFilterUPP filterProc = nil);
  267.  
  268.     void Send(TAEvent* future)    { this->Send(future, kAEWaitReply, kAENormalPriority, 0); };
  269.     void SendNoReply()            { TAEvent reply; this->Send(&reply, kAENoReply); }
  270.     void SendNoExecute();
  271.     
  272.     // misc
  273.  
  274.     void SuspendTheCurrentEvent();
  275.     void ResumeTheCurrentEvent(TAEvent* reply, AEEventHandlerUPP dispatcher = nil, long refCon = 0);
  276.     void SetTheCurrentEvent();
  277.  
  278.     void ResetTimer();
  279.         
  280.     void SpecifyThatParameterIsOptional(AEKeyword theOptionalKeyword);
  281.  
  282.     // get and set attributes for the Apple event
  283.  
  284.     TDescriptor GetAttribute(AEKeyword key, DescType desiredType = typeWildCard);
  285.     long GetLongAttribute(AEKeyword key);
  286.     long GetReturnID() { return this->GetLongAttribute(keyReturnIDAttr); };
  287.     long GetMessageTimeout() { return this->GetLongAttribute(keyTimeoutAttr); };
  288.     
  289.     void PutAttribute(AEKeyword key, TDescriptor attribute);
  290.     void PutOptionalDescriptor(AEKeyword key, TDescriptor data);
  291.     void PutLongAttribute(AEKeyword key, long attributeValue);
  292.  
  293.     /*
  294.             
  295.         OSErr GetAttribute(AEKeyword key, DescType desiredType, TDescriptor* descriptor);
  296.         OSErr GetAttributePtr(AEKeyword key, DescType desiredType, DescType *typeCode,
  297.                                 Ptr dataPtr, Size maximumSize, Size *actualSize);        
  298.         OSErr SizeOfAttribute(AEKeyword key, DescType desiredType, Size *size);    
  299.         OSErr PutAttributePtr(AEKeyword key, DescType desiredType, Ptr dataPtr, Size dataSize);    
  300.         
  301.     */
  302.     };
  303.  
  304.  
  305. //
  306. // AppleEventUtilities doesn't know anything about TAbstractScriptableObject
  307. // other than the fact that a class with that name exists.
  308. //
  309. class TAbstractScriptableObject;
  310.  
  311. typedef TTokenDescriptor (*MakeTokenDescriptorProcPtr)();
  312. typedef TTokenDescriptor (*ProcessDescriptorProcPtr)(TDescriptor);
  313. typedef TAbstractScriptableObject* (*MergeTokensProcPtr)(TAbstractScriptableObject* baseToken, TAbstractScriptableObject* mergeToken);
  314.  
  315. void InstallNullContainerCreationProc(MakeTokenDescriptorProcPtr creationProc);
  316. void InstallPreResolveProc(ProcessDescriptorProcPtr preResolveProc);
  317. void InstallMergeTokensProc(MergeTokensProcPtr mergeTokensProc);
  318.  
  319. TTokenDescriptor CreateNullContainerToken();
  320.  
  321.  
  322.  
  323. class TTokenDescriptor : public TDescriptor
  324.     {
  325. public:
  326.                     TTokenDescriptor();
  327.                     TTokenDescriptor(TDescriptor desc);
  328.  
  329.     // destructor & disposer
  330.     void            DisposeToken();
  331.  
  332.     TAbstractScriptableObject*    TokenHandle();
  333.  
  334.     void            AdoptToken(TTokenDescriptor& tokenDescriptor);
  335.     void            AdoptToken(TAbstractScriptableObject* tokenObject);
  336.     
  337.     };
  338.  
  339.  
  340.  
  341. #define FOREACHTOKEN(tokenList, tokenDescriptor)            \
  342.     TDescriptorLoop loop(tokenList);                        \
  343.     TAbstractScriptableObject* token;                                    \
  344.     while (loop.Next(tokenDescriptor, nil, nil) && ((token = tokenDescriptor.TokenHandle()) != nil))
  345.  
  346.  
  347.  
  348. #endif